<html>
<!--
  == This software is subject to the terms of the Eclipse Public License v1.0
  == Agreement, available at the following URL:
  == http://www.eclipse.org/legal/epl-v10.html.
  == You must accept the terms of that agreement to use this software.
  ==
  == Copyright (C) 2006-2011 Pentaho
  == All Rights Reserved.
  -->
<head>
    <link rel="stylesheet" type="text/css" href="stylesheet.css"/>
    <title>Pentaho Analysis Services: Configuration Guide</title>
</head>
<body>
<!-- doc2web start -->

<!-- page title -->
<div class="contentheading">Configuration Guide</div>
<!-- end page title -->

<!--
########################
##  Contents       #####
######################## -->
<h3>Contents</h3>

<ol>
	<li><a href="#Properties">Properties</a></li>
		<ol>
			<li><a href="#Property_list">Property list</a></li>
    	</ol>
    <li><a href="#Connect_strings">Connect strings</a></li>
		<ol>
			<li><a href="#Connect_string_syntax">Syntax</a></li>
    		<li><a href="#Connect_string_properties">Connect string properties</a></li>
    	</ol>
    <li><a href="#Cache_management">Cache management</a><ol>
			<li><a href="#Schema_cache">Schema cache</a></li>
    	</ol>
    <li><a href="#Memory_management">Memory management</a><ol>
			<li><a href="#Out_of_memory">Out of memory</a></li>
    	</ol>
    </li>
    <li><a href="#Logging">Logging</a><ol>
			<li><a href="#Test_Logging">Configuring log4j within Mondrian's test environment</a></li>
			<li><a href="#Statement_Logging">MDX and SQL Statement Logging</a></li>
    	</ol>
    </li>
</ol>
<!--
########################
##  1. Properties  #####
######################## -->
<h3>1. Properties<a name="Properties">&nbsp;</a></h3>

<p>Mondrian has a properties file to allow you to configure how it executes. The
<code>mondrian.properties</code> file is loaded when the executing Mondrian JAR detects it
needs properties, but can also be done explicitly in your code. It looks in
several places, in the following order:</p>
<ol>
  <li>In the directory where you started your JVM (Current working directory for
  JVM process, java.exe on Win32, java on UNIX/Linux).</li>
  <li>If there isn't mondrian.properties under current working directory of JVM
  process, Class MondrianProperties's classloader will try to locate
  mondrian.properties in all of its classpaths. So you may put <code>mondrian.properties</code>
  under <code>/WEB-INF/classes</code> when you pack Mondrian into a Java web application.
  The demonstration web applications have this configuration.</li>
</ol>

<p>These properties are stored as system properties, so they can be set during
JVM startup via <code>-D&lt;property&gt;=&lt;value&gt;</code>.</p>
<!--
###########################
##  1.1 Property list #####
########################### -->
<h3>1.1 Property list<a name="Property_list">&nbsp;</a></h3>

<p>The following properties in <code>mondrian.properties</code> effect the
operations of Mondrian.</p>

<p>Not all of the properties in this table are of interest to the end-user. For
example, those in the 'Testing' are only applicable if are running Mondrian's
suite of regression tests.</p>

<!-- doc2web include properties.html -->

<h3>Limit properties<a name="Limit_properties">&nbsp;</a></h3>

<p>Properties <code>mondrian.result.limit</code>, <code>mondrian.rolap.iterationLimit</code>
and <code>mondrian.rolap.queryTimeout</code> enforce runtime limits on the
time or space required to execute a query. If any of these limits are exceeded,
mondrian throws an exception which extends
<a href="api/mondrian/olap/ResultLimitExceededException.html">
mondrian.olap.ResultLimitExceededException</a>.</p>

<h2>Connect strings<a name="Connect_strings">&nbsp;</a></h2>

<h3>Connect string syntax<a name="Connect_string_syntax">&nbsp;</a></h3>

<p>Mondrian connect strings are a connection of property/value pairs, of the
form 'property=value;property=value;...'.</p>

<p>Values can be enclosed in single-quotes, which allows them to contain spaces
and punctuation. See the the
<a target="_blank" href="http://msdn.microsoft.com/library/en-us/oledb/htm/oledbconnectionstringsyntax.asp">
OLE DB connect string syntax specification</a>.</p>

<p>The supported properties are described below.</p>

<h3>Connect string properties<a name="Connect_string_properties">&nbsp;</a></h3>

<table class="grayTable" width="500">
    <tr>
        <th>Name</th>
        <th>Required?</th>
        <th>Description</th>
    </tr>
    <tr>
        <td>Provider</td>
        <td>Yes</td>
        <td><p>Must have the value &quot;Mondrian&quot;.</p></td>
    </tr>
    <tr>
        <td>Jdbc</td>
        <td rowspan="2">Exactly one</td>
        <td><p>The URL of the JDBC database where the data is stored. You must
        specify either <code>DataSource</code> or <code>Jdbc</code>.</p></td>
    </tr>
    <tr>
        <td>DataSource</td>
        <td><p>The name of a data source loaded via JNDI. The name must be a valid JNDI name, and the object referenced must implement the
        <a href="http://java.sun.com/j2se/1.5.0/docs/api/javax/sql/DataSource.html">javax.sql.DataSource</a> interface.
        You must specify either
        <code>DataSource</code> or <code>Jdbc</code>.</p></td>
    </tr>
    <tr>
        <td>JdbcDrivers</td>
        <td>Yes</td>
        <td><p>Comma-separated list of JDBC driver classes, for example,</p>

        <blockquote>
            <code>JdbcDrivers=sun.jdbc.odbc.JdbcOdbcDriver,oracle.jdbc.OracleDriver</code>
        </blockquote>
        </td>
    </tr>
    <tr>
        <td>JdbcUser</td>
        <td>No</td>
        <td><p>The name of the user to log on to the JDBC database. (If your JDBC
        driver allows you to specify the user name in the JDBC URL, you don't
        need to set this property.)</p></td>
    </tr>
    <tr>
        <td>JdbcPassword</td>
        <td>No</td>
        <td><p>The name of the password to log on to the JDBC database. (If your
        JDBC driver allows you to specify the password in the JDBC URL, you
        don't need to set this property.)</p></td>
    </tr>
    <tr>
        <td>Catalog</td>
        <td rowspan="2">Exactly one</td>
        <td><p>The URL of the catalog, an XML file which describes the schema: cubes, hierarchies, and so forth.
        For example,</p>

        <blockquote><code>
            Catalog=file:demo/FoodMart.xml</code></blockquote>

        <p>Catalogs are described in <a href="schema.html">the Schema Guide</a>.
        See also <code>CatalogContent</code>.</p></td>
    </tr>
    <tr>
        <td>CatalogContent</td>
        <td><p>An XML string representing the schema: cubes, hierarchies, and so forth.
        For example,</p>

        <blockquote><code>
            CatalogContent=&lt;Schema name=&quot;MySchema&quot;&gt;&lt;Cube name=&quot;Cube1&quot;&gt; ...
            &lt;/Schema&gt;</code></blockquote>

        <p>Catalogs are described in <a href="schema.html">the Schema Guide</a>.
        See also <code>Catalog</code>.</p></td>
    </tr>
    <tr>
        <td>CatalogName</td>
        <td>No</td>
        <td><p>Not used. If, in future, Mondrian supports multiple catalogs, this property
        will specify which catalog to use. See also <code>Catalog</code>.</p></td>
    </tr>
    <tr>
        <td>PoolNeeded</td>
        <td>No</td>
        <td><p>Tells Mondrian whether to add a layer of connection pooling.</p>

        <p>If the value &quot;true&quot; is specified, or no value is specified, Mondrian
        assumes that:</p>

        <ul>
            <li>connections created via the <code>Jdbc</code> property are not pooled,
            and therefore need to be pooled;</li>
            <li>connections created via the <code>DataSource</code> are already pooled.</li>
        </ul>

        <p>If the value &quot;false&quot; is specified, Mondrian does not apply
        connection-pooling to any connection.</p></td>
    </tr>
    <tr>
        <td>Role</td>
        <td>No</td>
        <td><p>The name of the <a href="schema.html#Access_control">role</a> to adopt
        for access-control purposes. If not specified, the connection uses a role
        which has access to every object in the schema.</p>
		<p>This property can contain multiple role names separated by commas. If
		so, queries in the connection execute with the sum of the privileges of
		all of the rules; the effect is the same as running under a
		<a href="schema.html#Union_roles">union role</a>, defined using the
		<code>&lt;Union&gt;</code> element in the schema file.</p>
		<p>If a role name contains a comma, escape the comma using an extra
		comma. For example, a connection created with</p>
		<blockquote>
			<p><code>Role='Pacific region manager,Europe,, Middle East and
			Africa manager'</code></p>
		</blockquote>
		<p>will execute with the combined privileges of the roles &quot;Pacific
		region manager&quot;, and &quot;Europe, Middle East and Africa manager&quot;.</p></td>
    </tr>
    <tr>
        <td>jdbc.*</td>
        <td>No</td>
        <td><p>Any property whose name begins with &quot;jdbc.&quot; will be added to the JDBC
        connection properties, after removing this prefix. This allows you to specify connection
        properties without a URL.</p>

        <p>For example, given the properties</p>

        <blockquote>
            <p><code>jdbc.Timeout=50; jdbc.CacheSize=1m</code></p>

        </blockquote>
        <p>Mondrian will create a JDBC connection using the properties
        {Timeout=&quot;50&quot;, CacheSize=&quot;1m&quot;}.</td>
    </tr>
    <tr>
        <td>UseContentChecksum</td>
        <td>No</td>
        <td><p>Allows mondrian to work with dynamically changing schema. If this property
            is set to <code>true</code> and schema content has changed (previous
            checksum doesn't equal with current), schema would be reloaded.
            The default is <code>false</code>.</p>
            <p>Could be
            used in combination with <code>DynamicSchemaProcessor</code> property.</p></td>
    </tr>
    <tr>
        <td>UseSchemaPool</td>
        <td>No</td>
        <td><p>Controls whether a new connection use a schema from the schema
        cache. If <code>true</code>, the default, a connection shares a schema
        definition (and hence also a cache of aggregate data retrieved by
        previous queries) with other connections which have a textually
        identical schema definition.</p>
        <p>If <code>false</code>, the connection has a private schema definition
        and cache.</p></td>
    </tr>
    <tr>
        <td>DynamicSchemaProcessor</td>
        <td>No</td>
        <td><p>The name of a class which is called at runtime in order to modify
        the schema content. The class must implement the
        <a href="api/mondrian/spi/DynamicSchemaProcessor.html">
            mondrian.spi.DynamicSchemaProcessor</a> interface. For example,</p>

        <blockquote>
            <code>DynamicSchemaProcessor =
            mondrian.i18n.LocalizingDynamicSchemaProcessor</code>
        </blockquote>

        <p>uses the builtin schema processor class
        <a href="api/mondrian/i18n/LocalizingDynamicSchemaProcessor.html">
        mondrian.i18n.LocalizingDynamicSchemaProcessor</a> to replace variables
        in the schema file, according to resource files and the current locale
        (see the <code>Locale</code> property).</p></td>
    </tr>
    <tr>
        <td>Locale</td>
        <td>No</td>
        <td><p>The requested Locale for the current session. The locale determines
        the formatting of numbers and date/time values, and Mondrian's error
        messages.</p>

        <p>Example values are &quot;en&quot; (English), &quot;en_US&quot;
        (United States English), &quot;hu&quot; (Hungarian). If Locale is not specified, then the name of system's default will be used, as per
        <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Locale.html#getDefault()">
        java.util.Locale#getDefault()</a>.</td>
    </tr>
    <tr>
        <td>JdbcConnectionUuid</td>
        <td>No</td>
        <td><p>A unique identifier for the connection. If this is set, Mondrian will look at this property and no other to determine whether two
data sources should be considered the same. You must ensure that connections will only share a JdbcConnectionUuid if they point to the same database.</p></td>
    </tr>
    <tr>
        <td>AggregateScanCatalog</td>
        <td>No</td>
        <td><p>The name of the database catalog to scan when loading aggregate tables. If this is not set, Mondrian will read all catalogs the database connection has access to when loading aggregate tables.</p></td>
    </tr>
    <tr>
        <td>AggregateScanSchema</td>
        <td>No</td>
        <td><p>The name of the database schema to scan when loading aggregate tables.  If this is not set, Mondrian will read all schemas the database connection has access to when loading aggregate tables.</p></td>
    </tr>
</table>
<p>Connect string properties are also documented in the
<a href="api/mondrian/rolap/RolapConnectionProperties.html">
RolapConnectionProperties</a> class.</p>

<h2>Cache management<a name="Cache_management"></a></h2>

<h3>Schema cache<a name="Schema_cache"></a></h3>

<p>To flush all schema definitions, use
the <a href="api/mondrian/olap/CacheControl.html#flushSchemaCache()">mondrian.olap.CacheControl.flushSchemaCache()</a>
method:</p>

<blockquote>
    <p><code>import mondrian.olap.*;<br>
    <br>
    Connection connection;<br>
    CacheControl cacheControl = connection.getCacheControl(null);<br>
    cacheControl.flushSchemaCache();</code></p>

</blockquote>
<p>The cache is only used when creating new connections; existing connections
retain their schemas.</p>
<p>
There are four connect string properties that control the use of the
Schema cache:
<code>UseSchemaPool</code>,
<code>UseContentChecksum</code>,
<code>CatalogContent</code> and
<code>DynamicSchemaProcessor</code>.
</p>

<p>The <code>UseSchemaPool</code> property controls whether or not the cache is used
regardless of the values of any of the other properties. If UseSchemaPool
is "false", then the cache is not used; each request for a new schema
object creates a new one (entailing the re-parsing of the schema definition
and re-scanning of the database for meta data and aggregate tables -
very slow, and, in addition, there is no reuse of the in-memory aggregate
cache).</p>

<p>Next, if <code>UseContentChecksum</code> is "true", then a check sum (MD5) is created
from the schema definition content (not URL) and it is this check sum
that is used as the key to lookup previously cached versions of the
schema definition. If two schema definitions produce different check
sums, then one can safely assume that they are different schemas (of course,
it is possible that only a comment or some whitespace in the schema
definition changed in which case the two schemas would actually be the
same, but because their check sums are different, different schema
objects are used). If UseContentChecksum is "false", then no check sum
is created and used as the lookup key, rather, a combination of
the connection attributes
"catalogUrl",
"connectionKey",
"jdbcUser",
"dataSourceStr"
or
"catalogUrl",
"dataSource"
are used to create the key.</p>

<p>If the <code>CatalogContent</code> is specified, then it is used as the schema
definition content. If, in fact, it is specified, then the value of
DynamicSchemaProcessor, if any, is ignored.</p>

<p>Finally, the <code>DynamicSchemaProcessor</code> connection string property is the
class name of a class that implements the DynamicSchemaProcessor
interface. If set, an instance of the class is created for each
schema request and its "processSchema" method is called which
returns the schema definition content.</p>

<h2>Memory management<a name="Memory_management"></a></h2>

<h3>Out Of Memory<a name="Out_of_memory"></a></h3>

<p>Java <code>OutOfMemoryError</code> errors have always been an issue with
applications. When the JVM throws an <code>Error</code> as
opposed to an <code>Exception</code> it is telling the application
that its world has ended and it has no recourse but to die.
Prior to Java5 there was not much one could do other
than buy 64-bit machines with lots of RAM and hope for the best.
For a multi-user, Mondrian environment with potentially very large
data-sets and clients that
can generate queries requesting arbitrarily large amounts of that
data, this can be an issue. This is especially the case when
Mondrian is being hosted on some corporate web-server; applications
that kill web-servers are not looked upon favorably by IT.
<p>
With Java5 (and Java6, etc.) there is alternative. An application
cay take advantage of
a new feature in Java5 allowing the application to be notified when
memory starts running low. This allows the application to take
preemptive action prior to an <code>OutOfMemoryError</code> being
generated by the Java runtime.
<p>
Mondrian takes advantage of this new feature. Rather than
passing an <code>OutOfMemoryError</code> to its client, it
will now stop processing the present query, free up data structures
associated with the present query and return a
<code>MemoryLimitExceededException</code> to the client.
The <code>MemoryLimitExceededException</code> is one of Mondrian's
<code>ResultLimitExceededException</code> which are used to communicate
with clients that a limit has been exceeded, in this case, memory
usage.
<p>
By default, for Mondrian running under Java5, this feature is
enabled and the "safety limit" is set at 90 percent, when
memory usage gets to with 90 percent of the maximum possible, the
the processing of the current query is stopped and a
<code>MemoryLimitExceededException</code> is return to the client.
See the Memory monitoring properties above on this page
for additional information.
<p>
Lastly, the gorilla in the closet. Java5 in its wisdom only allows
for one memory threshold notification level to be registered with the JVM.
What this means is if within the same JVM, some code registers
one level, say, at 80% (here I use percentages for ease of presentation
rather than number of
bytes which is what the Java5 API actually supports)
and some other code later on registers a level of
90%, then it is the 90% that the JVM knows about - it knows nothing
of the previously registered 80%. What this means is that the code
expecting to be notified when the memory level crosses 80%, won't be notified!<p>
For many applications that don't share their JVM with
other applications, this is not a problem, but for Mondrian is it
potentially an issue. Mondrian can be running in a Webserver and
Webservers can have more than one independent applications.
Each such application can register a different memory threshold
notification level.
In general, application-containing applications such as
web-servers or application-servers are a problem with the current
Java5 memory threshold notification approach.
At the current time, I do not know a way around this problem.


<h2>Logging<a name="Logging"></a></h2>
<p>
	Mondrian uses log4j for all information and debug logging.  When running
within an application server, Mondrian's log4j configuration is determined by
the server's or web application's log4j configuration. Please see
<a href="http://logging.apache.org/log4j/1.2/manual.html">log4j's documentation</a>
for a additional details.
</p>

<h3>Configuring log4j within Mondrian's test environment<a name="Test_Logging"></a></h3>
<p>
	When running outside an application server, log4j determines the location
of the log4j.xml file via the log4j.configuration java system property.   log4j
treats this string as a URL, so to have it detect the log4j file on the file
system, you must use the syntax "file:DIR/log4j.xml". Relative paths are
acceptible, so if you have your log4j.xml file in the root directory of
mondrian, "file:log4j.xml" will load the correct file.  You may specify the
log4j.configuration property in mondrian.properties, because Mondrian's ant
build file explicitly sets the property as a JVM system property when running
JUnit tests.
</p>

<h3>MDX and SQL Statement Logging<a name="Statement_Logging"></a></h3>
<p>
	The default log4j.xml file is configured so that a separate log file is
created for both MDX and SQL statement logging.  In the code, the MDX and SQL
strings are logged at the debug level, so to disable them you can set the log
level to INFO or any other level above debug.  Statement logging occurs within
the log4j categories "mondrian.mdx" and "mondrian.sql".  These categories log
the statements and how long they took to execute.  The SQL log also records the
number of results returned in the result set.
</p>

<p>For example, to trace both MDX and SQL statements, create a file
<code>log4j.properties</code> in the directory where you started mondrian
with the following contents:</p>

<blockquote>
    <pre># Set root logger level to DEBUG and its only appender to MONDRIAN.
log4j.rootLogger=WARN, MONDRIAN

# MONDRIAN is set to be a ConsoleAppender.
log4j.appender.MONDRIAN=org.apache.log4j.ConsoleAppender

# MONDRIAN uses PatternLayout.
log4j.appender.MONDRIAN.layout=org.apache.log4j.PatternLayout
log4j.appender.MONDRIAN.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

# Trace MDX and SQL statements
log4j.category.mondrian.mdx=DEBUG, MONDRIAN
log4j.category.mondrian.sql=DEBUG, MONDRIAN</pre>
</blockquote>

<p>Then mondrian with the argument
<code>-Dlog4j.configuration=file:log4j.properties</code> on the Java command
line.</p>

<p>Consider setting the property
<code><a href="api/mondrian/olap/MondrianProperties.html#GenerateFormattedSql">
mondrian.rolap.generate.formatted.sql</a>=true</code> in
<code>mondrian.properties</code> to make the format more
readable.</p>

<hr noshade size="1"/>
<p>
    Author: Julian Hyde; last modified April, 2011.<br/>
    Version: $Id$
    (<a href="http://p4web.eigenbase.org/open/mondrian/doc/configuration.html?ac=22">log</a>)<br/>
    Copyright (C) 2006-2011 Pentaho
</p>

<br />

<!-- doc2web end -->

</body>
</html>
